package com.xrui.hbase;

import java.io.Closeable;
import java.io.Flushable;
import java.io.IOException;

/**
 * Interface for performing increments on a HBase table.
 * <p>
 * <p>
 * Incrementer provides a method for modifying the value of a counter given
 * an entity id, column family, column qualifier, and a signed long amount by which
 * to modify the counter.  Increment does not support setting the timestamp of the
 * data to write, and returns the newly incremented cell.
 * </p>
 * <p>
 * <pre>
 *   final Incrementer incrementer = myHBaseTable.openTableWriter();
 *   incrementer.increment(entityId, columnFamily, columnQualifier, amount);
 * </pre>
 * <p>
 * This interface is not used alone but is bundled within {@link TableWriter}.
 */
public interface Incrementer extends Closeable, Flushable {
    /**
     * Atomically increments a counter in a HBase table.
     * <p>
     * <p>Throws an exception if the specified column is not a counter.</p>
     *
     * @param entityId  Entity ID of the row containing the counter.
     * @param family    Column family.
     * @param qualifier Column qualifier.
     * @param amount    Amount to increment the counter (may be negative).
     * @return the new counter value, post increment.
     * @throws IOException on I/O error.
     */
    HBaseCell<Long> increment(EntityId entityId, String family, String qualifier, long amount)
        throws IOException;
}
